Formatting and Validating Controls

This topic describes the procedure to format controls.

Each data record that is displayed in a control comprises a description and a value. The description is what is displayed in the control during run time. The value associated with each data record is used at the backend for transactions related to the data record.

It is possible to format the description and value of a control, and specify validation rules for data-entry controls. For a data-bound control, the formatting and validation settings defined for its reference field in the WSDL or XSD are automatically applied. However, in some cases, you may need to set the formatting of a control at run time. It is possible to do so using the format, getFormatType, and setValue (run time) methods.

During design time, you can specify the format and validation for a control as follows. This feature is available for the Input, Textarea, Output, List, and Select controls.

1. Open the XForm in the XForms Designer.
2. To format and validate a control, right-click the control and select Format. The Formatting Options dialog box appears. It displays the Control ID and Data Type fields, and the Format and Validation tabs.
3. Select the type of data value supported for the control, from the Data Type drop-down list:
   
   • Integer: A numeric data type that can hold exact integer values. An integer is a 32-bit, signed (positive or negative) whole number without decimals. The Integer data type includes the XSD-defined types such as i1, ui1, i2, ui2, i4, and i8.
   • Float: A numeric data type used to store floating-point values. This type is useful for applications that need large numbers but do not need precise accuracy. This data type includes the XSD-defined types such as r4 and r8.
   • Double: A numeric data type used to store floating-point values. It offers greater precision and can store larger numbers than the Float data type.
   • Decimal: An exact numeric data type. It can accurately represent very large or very precise decimal numbers. This type is useful for applications (such as accounting) where rounding-off errors must be avoided.
   • Amount: A numeric data type that are represents currency.
   • String: Contains a sequence of characters such as letters, numbers, and punctuation marks.
   • Date: A data type used for date and time.

     Note:
     At run time, you can specify the date by entering the number of days prior to or ahead of the current date. For example, enter '+1' to specify tomorrow's date, or enter '-7' to specify a date from the week gone by.

   • HexBinary: Represents arbitrary, hex-encoded binary data. The value space of HexBinary is a set of finite-length sequences of binary octets.
   • base64Binary: Represents Base64-encoded arbitrary binary data. The value space of base64Binary is a set of finite-length sequences of binary octets.
   • AnyURI: Represents a Uniform Resource Identifier Reference (URI). An AnyURI value can be absolute or relative, and may have an optional fragment identifier (that is, it may be a URI Reference). This type can be used to specify the intention that the value fulfills the role of a URI. The selected option displays in the Data Type drop-down list.
4. Select Required in the Formatting Options dialog box to set the field as mandatory.
5. Make appropriate modifications in the Format tab:
   
   • Select an option from the Locale drop-down list to specify your language and country.

     Note:

     • If not defined, the settings of the client computer are used as Locale settings.
     • Changing the Locale also changes the date and currency settings accordingly.
   • Select a format for currency values from the Currency drop-down list. This option is enabled only for the Amount data type.
   • Select an option from the Time Zone drop-down list to specify your time zone. This option is enabled only for the Date data type.
   • Specify the number of decimal places to allow in an input value in the Number of Decimal field. This option is enabled for the Float, Double, and Amount data types.
   • Select a predefined format for the specified data type from the Predefined Format drop-down list. Predefined formats are available for the Integer, String, and Date data types.
   • Specify a format in the Specific Format field to use a custom format.
   • Select a data-alignment option from the Data Alignment drop-down list.
   • Select a display format for positive values from the Positive Pattern drop-down list. This option is enabled only for the Amount data type.
   • Select a display format for negative values from the Negative Pattern drop-down list.

     Note:
     Formatting is supported for various data types such as Integer, Float, Amount, String, and Date.

6. Make appropriate modifications in the Validation tab:
   
   • Specify the minimum value allowed in the Minimum Inclusive Value field.
   • Specify the maximum value allowed in the Maximum Inclusive Value field.
   • Specify the minimum length allowed in the Minimum Length field.
   • Specify the maximum length allowed in the Maximum Length field.
   • Specify the characters that are allowed to be used in the Legal Character Set field. You can use regular expressions to specify the characters. For example,
     
     • to allow a string that starts with only an alphabet, you can use ^[a-zA-Z].
     • to allow only alphanumeric values, you can use ^[a-zA-Z0-9]+$.
     • to allow a number that is three characters in length, you can use ^\d{3}$.
   • Specify the characters that are not allowed to be used in the Illegal Character Set field. You can use regular expressions to specify the characters. For example,
     
     • to avoid space, you can specify \s.

     • to avoid specific special characters, you can specify [!@#$%^&*()].

       Note:
       You can use the xforms-onvalidate event to programmatically create additional validations for a control.

7. Make the appropriate modifications in the Messages tab.
   
   • Type the message to be displayed, if the validation of the corresponding constraint fails, in the Message column.

     Note:

     • The insertions specified as {0} in a message will be replaced at run time with the respective property of the control, depending on the constraint. When a translated XForm is viewed, the insertions in a message ( {0} , {1}) are translated as well.
       For example, consider a mandatory control with Data Type as 'integer' and a validation message that states 'Enter a non-empty value for {0}'. Here, the insertion will be replaced with the translated label at run time.
     • All default messages andtooltips are bundled in the cordys.Xforms.messages.xml message bundle. The Platform Administrator can specify translations for the message bundle by creating files such as cordys.Xforms.messages_<language code>.xml. For example, for translation to the Dutch language, the translated message bundle is cordys.Xforms.messages_nl_NL.xml.
8. Click OK to save all changes.

   Note:
   Clicking Set default from XSD restores the default settings specified for the control's reference field in the WSDL or XSD. This button is enabled only for data-bound controls.

The formatting and validation conditions for the control are set as specified.